home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / os2 / o2d011.zip / O2D.DOC next >
Text File  |  1992-11-14  |  7KB  |  177 lines
  1.  O2D             Copyright (c) 1992 Bruce E. Högman.        Ver 1.0
  2.                  All Rights Reserved.                       92-11-13
  3.  
  4.  FUNCTION:
  5.  
  6.     O2D is an OS/2 program that issues a DosStartSession call to start a
  7.     foreground fullscreen DOS session and to pass an ENVIRONMENT
  8.     constructed from a user-specified ASCII text file containing a list
  9.     of variables to SET.  The invoked DOS session is a CHILD of the OS/2
  10.     parent session containing O2D. The new session requests foreground
  11.     execution, but OS/2 will not honor this unless the parent session is
  12.     currently in the foreground.  The parent session waits for the new
  13.     session to terminate.
  14.  
  15.     The intended use of this program is to allow an OS/2 program, .CMD
  16.     or REXX to invoke a DOS .BAT file and wait for its termination.  A
  17.     specific application is to allow use of .BAT files common to both
  18.     OS/2 and DOS users of LAN services, for example.
  19.  
  20.     The environment constructed is used only by the operating system DOS
  21.     session manager during its initialization of the target DOS session.
  22.     This processing supports setup of target DOS session with the same
  23.     functionality as provided by the launching of a DOS session from the
  24.     desktop where the DOS session is defined by a folder.
  25.  
  26.  ** NOTE:
  27.  
  28.     To establish a DOS environment containing PATH and SET variables for
  29.     use by the target DOS application program, start a .BAT file instead
  30.     of a .EXE or .COM file as the target of the O2D program and use
  31.     appropriate SET commands in the .BAT file that setup the environment
  32.     variables for the target application.
  33.  
  34.     Example of .BAT SET commands for BorlandC compiler:
  35.  
  36.       SET INCLUDE=C:\BORLANDC\INCLUDE;C:\MYC\INCLUDE
  37.       SET LIB=C:\BORLANDC\LIB
  38.       PATH=C:\BORLANDC\BIN;%PATH%
  39.  
  40.  
  41.     Example of ASCII Environment File records:  (shows all keys)
  42.     Only some of the keywords below are usually used:
  43.  
  44.         DOS_BACKGROUND_EXECUTION=ON
  45.         DOS_BREAK=OFF
  46.         DOS_DEVICE=   /* device.sys filename */
  47.         DOS_FCBS=16
  48.         DOS_FCBS_KEEP=8
  49.         DOS_FILES=20
  50.         DOS_HIGH=ON
  51.         DOS_LASTDRIVE=J
  52.         DOS_RMSIZE=640
  53.         DOS_SHELL=D:\OS2\MDOS\COMMAND.COM D:\OS2\MDOS /P
  54.         DOS_STARTUP_DRIVE=  /* filespec for VMDISK DOS file */
  55.         DOS_UMB=ON
  56.         DOS_VERSION=        /* special DOS settings required for app */
  57.         DPMI_DOS_API=ENABLED
  58.         DPMI_MEMORY_LIMIT=3
  59.         DPMI_NETWORK_BUFF_SIZE=8
  60.         EMS_FRAME_LOCATION=AUTO
  61.         EMS_HIGH_OS_MAP_REGION=32
  62.         EMS_LOW_OS_MAP_REGION=384
  63.         EMS_MEMORY_LIMIT=2048
  64.         HW_NOSOUND=OFF
  65.         HW_ROM_TO_RAM=OFF
  66.         HW_TIMER=OFF
  67.         IDLE_SECONDS=15
  68.         IDLE_SENSITIVITY=75
  69.         KBD_ALTHOME_BYPASS=OFF
  70.         KBD_BUFFER_EXTEND=ON
  71.         KBD_CTRL_BYPASS=OFF
  72.         KBD_RATE_LOCK=OFF
  73.         MEM_EXCLUDE_REGIONS=
  74.         MEM_INCLUDE_REGIONS=
  75.         MOUSE_EXCLUSIVE_ACCESS=OFF
  76.         PRINT_TIMEOUT=15
  77.         VIDEO_FASTPASTE=ON
  78.         VIDEO_MODE_RESTRICTION=NONE
  79.         VIDEO_ONDEMAND_MEMORY=ON
  80.         VIDEO_RETRACE_EMULATION=OFF
  81.         VIDEO_ROM_EMULATION=OFF
  82.         VIDEO_SWITCH_NOTIFICATION=ON
  83.         VIDEO_WINDOW_REFRESH=1
  84.         XMS_HANDLES=32
  85.         XMS_MEMORY_LIMIT=2048
  86.         XMS_MINIMUM_HMA=0
  87.  
  88.     O2D provides support for the keywords in the DOS SESSION parameters
  89.     in the program folder, thus giving .CMD and REXX programs the same
  90.     DOS application features as provided by the program folder DOS
  91.     SESSION parameters.
  92.  
  93.  
  94.  CMD LINE:
  95.  
  96.     O2D pgm_spec  [/env:env_filespec] [/cd:cwd_spec] [target app cmd line]
  97.  
  98.     O2D /? displays help information on syntax.
  99.  
  100.     Example:  (the next several lines would be entered as a single cmd)
  101.  
  102.     O2D
  103.         d:\os2\apps\borlandc.bat d:\os2\apps\borlandc.ini
  104.         .... borlandc bc.exe cmd line parameters ...
  105.  
  106.  
  107.  PROCESSING LOGIC:
  108.  
  109.     1.  Process command line operands from left to right.
  110.         The first operand is the target program name or .bat file name.
  111.         The keyword operands are the /env: and /cwd: operands that
  112.         name the environment variable values file and the current
  113.         working directory.
  114.  
  115.         The /cwd: operand is acted upon 1st if it is present.  This
  116.         allows you to specify the program file/.bat file and the /env:
  117.         environment file name in relation to that /cwd: path.  If an
  118.         error occurs in attempting to chdir to the target cwd, the
  119.         processing halts.
  120.  
  121.         If a /cwd: operand is present, then O2D does a chdir to the
  122.         target directory.  After O2D starts the DOS session, it will
  123.         return to the drive and directory current at the time it began
  124.         execution.
  125.  
  126.     2.  Verify the target program file or .bat file exists.  Halt if
  127.         that file cannot be read.
  128.  
  129.     3.  Read & process env_spec file, constructing environment string to
  130.         pass to DosStartSession.
  131.  
  132.     4.  Issue DosStartSession call.
  133.  
  134.     5.  Wait for CHILD session to terminate using DosReadQueue to read
  135.         contents of termination queue defined prior to DosStartSession.
  136.         Note that the DosWaitChild function does not work for OS/2 to
  137.         DOS via DosStartSession.  If the user did not specify /nowait,
  138.         this wait step is by-passed, and the invoked DOS session runs
  139.         as an independent session.  If a wait is done, then the child
  140.         session is selected when the user selects O2D session from the
  141.         tasklist, and focus returns to O2D upon termination of the DOS
  142.         child session.
  143.  
  144.     6.  Restore the default drive and current directory for O2D that
  145.         was in effect when O2D started execution.
  146.  
  147.  ENABLING EXTENDED HELP DISPLAY
  148.  
  149.     If you copy the O2D.INF file to one of the directories in your
  150.     BOOKSHELF=  path, you can tell O2D to display the extended
  151.     structured help file by issuing the command:  O2D /? You can also
  152.     define a folder object in your Information folder that has:
  153.  
  154.        Program:              VIEW.EXE
  155.        Optional Parameters:  O2D.INF
  156.  
  157.     If you don't copy the O2D.INF file to a BOOKSHELF directory, then
  158.     you must specify the complete path to the O2D.INF file in the above
  159.     parameter value.
  160.  
  161.  TECHNICAL NOTES:
  162.  
  163.    The queue name used is \QUEUES\O2D\xxxx where xxxx is the thread
  164.    ordinal number for the current thread, which is unique in the system.
  165.    This permits multiple uses of O2D without any collisions in use
  166.    of queue names.  The termination queue is used to provide
  167.    synchronization with the child session.
  168.  
  169.    The usual DosWaitChild function does not support OS/2->DOS WAIT.  The
  170.    usual use of DosWaitChild is in conjunction with DosExecPgm function.
  171.    However, DosExecPgm cannot be used to start a session of DOS type
  172.    from an OS/2 session, hence the use of DosStartSession with the
  173.    complex "wait" processing.
  174.  
  175.    O2D issues DosReadQueue with wait, which does not return control to
  176.    itself until there is an entry in the termination queue.
  177.